"""Swagger 文档模块

提供离线 Swagger UI 支持。
"""
import logging
from fastapi import FastAPI
from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.responses import HTMLResponse

logger = logging.getLogger(__name__)


def add_offline_swagger_docs(app: FastAPI) -> None:
    """注册离线 Swagger UI 页面 (/docs)"""

    @app.get("/docs", include_in_schema=False, response_class=HTMLResponse)
    async def custom_swagger_ui_html():
        js_url = "/static/swagger-ui-bundle.js"
        css_url = "/static/swagger-ui.css"
        favicon_url = "/static/favicon.ico"

        logger.debug("Swagger UI 静态资源: %s, %s, %s", js_url, css_url, favicon_url)

        return get_swagger_ui_html(
            openapi_url="/openapi.json",
            title=f"{app.title} - Swagger UI (离线版)",
            swagger_js_url=js_url,
            swagger_css_url=css_url,
            swagger_favicon_url=favicon_url
        )
